introduction to rmarkdown

Anna Krystalli

Instituto de Ecología, UNAM 31 Aug. 2016

https://annakrystalli.github.io/UNAM/rmarkdown.nb.html

@annakrystalli | annakrystalli@googlemail.com

introduction

markdown .md

stripped down html

• intended to be as easy-to-read and easy-to-write as possible.
• intended for one purpose: to be used as a format for writing for the web.
• syntax is very small, corresponding only to a very small subset of HTML tags.

focus on communicating & disseminating

• formatting handled automatically
• clean and legible across platforms and outputs

structure of a website

rmarkdown .Rmd

rmarkdown integrates:

– a documentantion language (.md)

with:

– a programming language (R)

enables literate programming

single document to integrate data analysis with textual representations, linking data, code, and text

outputs

it’s already everywhere!

• github READMEs; eg rOpensci taxise README

• stackoverflow: eg plot coordinates on a map

• github.io websites: eg Andy South’s blog

---

Rmarkdown & reproducibility

Computational science has led to exciting new developments:

• Technology is increasing data collection throughput; data are more complex and highdimensional
• Existing databases can be merged to become bigger databases
• Computing power allows more sophisticated analyses, even on “small” data
• For every field “X” there is a “Computational X”

Increasing computational complexity of analyses:

has exposed limitations in our ability to evaluate published findings.

• Even basic analyses difficult to describe

• Errors more easily introduced into long analysis pipelines

• Knowledge transfer is inhibited

• Results are difficult to replicate or reproduce

• Complicated analyses cannot be trusted

calls for reproducibility

Reproducibility has the potential to serve as a minimum standard for judging scientific claims when full independent replication of a study is not possible.

• fully scripted analyses
• make code and data available

a reproducible workflow

reproducibility limitations

• top down
• downstream (post publication)

• ultimately does not address the key question:

  can we trust these results?

evidence based science

evdence needs:

• documenting
• linking
• communicating

rmarkdown can integrate tools, processes and outputs into evidence streams that are easily shareable

at all stages of scientific process

simple tools:

low hanging fruit

• begin at the start of the process
• document & interlink evidence streams
• explore and communicate!

empower your code and data

Science and the web

the web is for sharing!

Executive summary of the first ever website

why sharing is important

To help solve these problems, we make a number of suggestions including providing blog posts or videos to explain new methods in less technical terms, encouraging reproducibility and code sharing, making wiki-style pages summarising the literature on popular methods, more careful consideration and testing of whether a method is appropriate for a given question/data set, increased collaboration, and a shift from publishing purely novel methods to publishing improvements to existing methods and ways of detecting biases or testing model fit. Many of these points are applicable across methods in ecology and evolution, not just phylogenetic comparative methods.

examples

report

code documentation

method collation

interactive documents

presentations

---

Let’s go have a look

Open your first .Rmd!!

---

Elements of .Rmd

YAML header

outputs

themes

http://bootswatch.com/

---

md basics

text

    normal text

normal text

    *italic text*

italic text

    **bold text**

bold text

    ***bold italic text***

bold italic text

    superscript^2^

superscript²

    ~~strikethrough~~

strikethrough

headers

unordered lists

ordered lists

quotes & code

> this text will be quoted

this text will be quoted

`this text will appear as code` inline

this text will appear as code inline

a <- 10

    the value of parameter *a* is `r a`

the value of parameter a is 10

images

    ![](https://www.rstudio.com/wp-content/uploads/2015/01/rmarkdown-cheatsheet-2-e1457627578814.png)

    ![](assets/cheat.png)
    

resize images

    <img src="assets/cheat.png" width="200px" />

basic tables

Table Header  | Second Header
------------- | -------------
Cell 1        | Cell 2
Cell 3        | Cell 4 

Table Header	Second Header
Cell 1	Cell 2
Cell 3	Cell 4

online .md table converter

links

[Download R](http://www.r-project.org/)
[RStudio](http://www.rstudio.com/)

Download R

RStudio

.md resources

offical markdown documentation

Rmarkdown documentation

Rstudio Rmarkdown cheatsheet

github.io websites: eg Andy South’s blog

Reproducible Research coursera MOOC

Producing html documents from .R scripts using knitr::spin

chunks

R code chunks can be used as a means render R output into documents or to simply display code for illustration

options

for more details see http://yihui.name/knitr/

set default options

knitr::opts_chunk$set(echo = TRUE, warning = F, message = F)

---

extras

knitr::kable() tables

require(knitr)
data(airquality)
kable(head(airquality), caption = "New York Air Quality Measurements")

New York Air Quality Measurements

Ozone	Solar.R	Wind	Temp	Month	Day
41	190	7.4	67	5	1
36	118	8.0	72	5	2
12	149	12.6	74	5	3
18	313	11.5	62	5	4
NA	NA	14.3	56	5	5
28	NA	14.9	66	5	6

DT::datatable() tables

require(DT)
data(airquality)
datatable(airquality, caption = "New York Air Quality Measurements")

plotly

library(plotly)

set.seed(100)
d <- diamonds[sample(nrow(diamonds), 1000), ]

p <- ggplot(data = d, aes(x = carat, y = price)) +
  geom_point(aes(text = paste("Clarity:", clarity)), size = 1) +
  geom_smooth(aes(colour = cut, fill = cut)) + facet_wrap(~ cut)

ggplotly(p)

shiny

http://shiny.rstudio.com/

rpubs

http://rpubs.com/

---

Exercise

your mission

create your first .Rmd!

• choose some data eg:
  • datasets package
  • data(package = .packages(all.available = TRUE))
  • Caroline Thomson’s blue tit data
• show us some data in a table
• plot some data
• write a bit about what you did
• publish it on rpubs. Add you link to our googledoc

see my example: beavers! html - raw .Rmd